Pascal Super Library/Pascal Super Library (CW International)(1997).bin/LIBRARY/SLTPU70C/WHATS.NEW

Text File | 1993-09-16 | 22KB | 489 lines

What's New in SLTPU?

Version 3.5, September, 1993
----------------------------
The main new features in Searchlight 3.5 are expanded file descriptions,
file attachments to messages, and new internal RIP support. These changes
affect several of the data files in minor ways, and also result in some
additions to the function suite.


New CONFIG Switches:

Several new CONFIG variables are available. These correspond directly to
new features on the CONFIG program menus:

       PrivateAttach: AttribSet;   { Can attach file to private message }
       PublicAttach: AttribSet;    { Can attach file to public message }
       AttachPath: string[45];     { File attach path }
       NoGreeting: boolean;        { If set, disable login greeting }
       MaxFileDescrip: Integer;    { Max. size of file descriptions }
       HighAscii: boolean;         { Support high ascii chars? }


Binary File Attach:

Each message in a Searchlight 3.5 system can have a binary file attached
to it. If a message has a file attachment, the filename is stored in the
message header in this field:

       fattach: string[12];  { attached file, if any }

Notice that this field stores only a filename, and not a path. The editor
in Searchlight 3.5 will only allow a legal DOS filename to be stored here.
If there is no file attached, this field contains a blank string.

In order to access an attached file while reading a message, you need to
also retrieve the "File attach path", which is found in the CONFIG file:

       AttachPath: string[45];          { File attach path }

By concatenating the attach path with the filename, you can construct a
complete path to the attached file for any message. When attempting to
access an attached file, be sure to build error checking into your code so
that your program doesn't crash in case the file does not exist (for
example, the file may have been manually deleted by the Sysop; this is
considered normal and should not produce an error).

When a message that contains a binary file attachment is killed with the
KillMsgId or AutoTrim procedures, the attached file is automatically
deleted (unless the message is a carbon-copy, in which case the file is
deleted when the last copy of the message is deleted).

To post a message with a file attachment:
  (1) Copy or move the file into the attach file path (cf.Attachpath)
  (2) Store the filename in the message header (header.fattach)
  (3) Save the message

Be sure that the filename placed in the header is a legal DOS filename which
does not contain any pathnames or drive letters.

To add a file attachment to an existing message:
  (1) Copy or move the file into the attach file path
  (2) Retrieve the message header of the desired message
  (3) If the message already has a file attachment, delete the file
  (4) Store the new filename in the header, and save the header

A boolean field called 'Fretain' is included in the message header. If set
to True, the kill functions will not delete the attached file. Set this
field only in special circumstances where you want to delete a message, but
retain the attached file.


Long File Descriptions:

Each file in Searchlight 3.5 can have an "extended" file description of
up to 400 lines associated with it. Searchlight stores these extended
descriptions by creating a new file for each directory -- the new file
ends with the extension '.EDF', and is stored in the same place as the
directory's .SL2 file. The .EDF file stores text in the same format as a
subboard .MSG file, including text compression, and is therefore a highly
efficient way of storing file descriptions of varying lengths. The .EDF
file is created automatically when a directory is opened, if it does not
already exist.

An extended file description is indicated by a pointer in the message header:

       EdfTxt: longint;        { pointer to extended description }

If this pointer is nonzero, it indicates that an extended description exists
for the file. The following new functions are included in the DIR unit for
handing extended descriptions:

Procedure GetDescription (d: longint; var msg: msgptr);
 Function SaveDescription (msg: msgptr): longint;
Procedure KillDescription (d: longint);

Notice that extended descriptions are saved and retrieved into variables of
type MsgPtr -- the same type of variable that is used for storing and
reading messages. To get an extended file description, call GetDescription
with the EdfTxt pointer and an uninitialized variable of type msgptr:

  GetDescription(filerecord.edftxt,msg);

The resulting message variable contains the text of the extended description.
For more details about the MsgPtr type, see examples of retrieving messages
in the FILEDEF.REF document and the sample programs.

Note: Check to see if the MsgPtr variable is Nil after a call to this
function; if so, proceed as though no description is available. The call
could return a nil value if the EdfTxt pointer contained garbage, such
as if the record was saved by a program which was not aware of this pointer
and did not clear its value to zero before saving the record.

Remember to dispose of the extended description text when you are done with
it, by calling the DisposeMsg function. This frees the memory used to store
the description text.

The SaveDescription function stores an extended file description in the
directory's EDF file. Pass the function a variable of type MsgPtr that has
been built to contain the description text. The result is a pointer, which
should be loaded directly into the message header. Note that this function
allows you to handle description texts separately from files: it is up to
you to make sure you manage the descriptions and files together. The correct
way to add a file to the Searchlight directory with an extended description:

  (1) Create the data record for the file and the description text.
  (2) Save the description text with the SaveDescription function. Store
      the result in the EdfTxt field of the data record.
  (3) Add the data record to the directory file (AddFile function).

The KillDescription function is necessary only if you wish to edit an
existing extended description. It's not necessary to explicitly call this
function before deleting a file, because the DeleteFile function calls it
if necessary. When editing a file with an extended description, the proper
procedure is:

  (1) Load the old description into memory and edit it.
  (2) Kill the old description with the KillDescription function.
  (3) Save the modified description with SaveDescription. Store the
      result of the function in the file's data record.
  (4) Save the file's data record back to disk (so that the updated
      pointer is saved).

If you are replacing the description with something completely new, then
there is no need to load the old description.

Note: If you are saving or adding a file without an extended description,
be sure to store a value of 0 in the EdfTxt field.

Old vs. New descriptions: Searchlight 3.5 still uses the "short" file
description (40 character description in the message header). The old
two-line extended description (field 'Edescrip') is no longer used to
store descriptions, but is supported when reading old directories. In order
to maintain compatibility with both old and new directory formats:

  (1) When reading files, check for an extended description in EdfTxt
      first. If one is present, use it, and ignore the contents of the
      old Edescrip fields.

  (2) When saving or updating files, always store extended descriptions with
      the SaveDescription function, not in the Edescrip fields. Do this even
      if the extended description is only one or two lines. If updating an
      old entry, copy the data from the Edescrip field into a MsgPtr type
      variable, and re-save it as an extended description.

Note: See SAMPLE6.PAS for an example of working with long descriptions.


RIP Style Definitions:

Searchlight 3.5 introduces a new data file, RIPSTYLE.SL2. This file stores
the RIP styles, as defined in the CONFIG program. It also stores the RIP
General Setup information from the CONFIG program.

Two new files are included with the SLTPU library to support RIP styles:

  STYLEDEF.TPU
  STYLEDEF.REF

The STYLEDEF unit file defines data types for the RIP style records. It
also contains procedures for opening and closing the RIPSTYLE.SL2 file and
managing a stack of styles in use. STYLEDEF.REF is a reference file that
contains the actual record layout and type definitions managed by the
function calls.

For more information about STYLEDEF.TPU, see the SLTPU.REF file included
in this archive.



Version 3.0, March, 1993
------------------------
Searchlight 3.0 adds new functions to the modem interface including a string
output function. See MODEM.PAS and MODEM.DOC for more information.

Searchlight 3.0 adds Netmail support to Searchlight, as well as other
changes to the file structures. Note that none of the files has changed size
and no existing fields have changed location; therefore, programs written
for Searchlight 2.15 and 2.25 remain compatible with Searchlight 3.0 (the
only exception to this are programs that access the external protocol
definitions; see note below).

The data structure changes between version 2.25 and 3.0 are outlined here
for your convenience.


Type Definitions:

     RSbaud = (B110,B150,B300,B600,B1200,B2400,B4800,B9600,B19200,B38400,
               b7200,b12000,b14400,b16800);

The RSBaud type is extended to include support for additional baud rates.
Notice that the new rates are added to the end of the type; therefore the
ordinal numbers for B9600, B19200 and B38400 are unchanged. However, be
alert to the fact that less-than or greater-than comparisons based on the
ordinal values won't produce the expected results; in other words, if B1
equals B14400 and B2 equals B19200, the expression "if B1<B2" will produce
FALSE, since the ordinal value of B14400 is greater than the ordinal value
of B19200.


     ProtocolType = (Extern,XSUM,XCRC,X1K,ZMODEM);
     ExProtocol = record
       name: string[40];      { protocol name }
       sendcmd: string[72];   { send command }
       rcvcmd: string[72];    { receive command }
       source: ProtocolType;  { type of protocol }
       extra: string[19];     { expansion room }
     end;

The structure for protocol types has a new "source" value added to it. This
allows protocols defined in the CONFIG file to be either internal or
external protocols. By default, existing external protocols are assigned
"Extern" as the source type.

See the note below with reference to the 'Proto' variable in the CONFIG
file.


     AutoDoorType = record   { automatic door }
       command: string[60];
       directory: string[60];
       commtype: byte;
       abort: byte;
       writeprot: boolean;
       dropfile: byte;   { 0=None 1=PCB14 2=PCB12 3=DOOR.SYS 4=DORINFOx.DEF }
       pause: boolean;   { pause after door executes? }
       extra: string[8];
     end;

The AutoDoor type is mostly unchanged. Note that the 'dropfile' type has new
values corresponding to the new formats available in Searchlight 3.0.


     FidoAddressType = record
       node,net,zone,point: word;
     end;

     AddressType = record    { message address information }
       data: string[40];   { address data }
       atype: byte;        { 0=forward 1=incoming netmail 2=outgoing netmail }
     end;

'FidoAddressType' is used to record the default fidonet addresses for
outgoing netmail. The more generic 'AddressType' is used inside message
headers to indicate the source or destination address for netmail messages.
More information about netmail messages is outlined below.



CONFIG File:

       Proto: array[1..MaxProto]
         of exprotocol;        { external protocols setup }

The array of protocols in the CONFIG file is now called 'Proto' instead of
'ExProto' because it defines ALL the protocols available, not just the
external protocols. Also, the full 15 entries in this array are now used.

The 'ExProtocol' type defines a 'source' variable to indicate internal
protocols, including the new internal Zmodem protocol, as outlined above.
When Searchlight 3.0 first runs, it installs the three Searchlight 2.25
default protocols -- Xmodem, Xmodem/CRC, and Xmodem/1K -- into the first
three locations in the Proto array, bumping the existing internal protocol
definitions down three spots. Once this is accomplished, your programs can
access all of the protocols defined for a system directly in this array.
Note that the protocol number defined in USER records refers DIRECTLY to
this array now, and does not need to be checked to see if it is greater than
3 or less than 3 as in previous versions.


       MaxRegNode: integer;    { max nodes permitted by reg number }

This variable will give you the maximum number of lines permitted by the
customer's registration license (1 for single line systems, 3 for 1 to 3
line systems, 10 for 10 line systems, and MAXINT (32767) for unlimited node
licenses). This is a read-only value. Changing it will have no effect on
Searchlight, as the value is initialized each time Searchlight starts up or
returns from a door.


       Subboardset: string[57];     { name of active subboard list }

This variable stores the name of the text file used to select the order of
the subboards (either MAIN.SUB, or a filename used with internal command
200).


       AnsiDetect: boolean;             { Set if ANSI was auto-detected }
       RipTest: boolean;                { Set if RIP should be tested for }
       RipOn: boolean;                  { Set if RIP is available }
       RipVers: array[1..3] of byte;    { Rip version }

'AnsiDetect' is true if the LOGIN program was able to auto-sense ANSI when
the user connected. It is false otherwise. Note that 'AnsiDetect' may be
false even if the user has manually selected ANSI mode, and it may be true
even though the user has manually selected non-ANSI mode.

'RipTest' corresponds directly to the "Enable RIP Graphics?" switch in the
CONFIG file. If true, Searchlight tries to auto-detect RIP graphics at login
and allows RIP to be selected as a terminal mode. If false, Searchlight does
not sense RIP or offer the RIP support option.

'RipOn' is set only if Searchlight is actually in RIP graphics mode; that
is, if the current caller has a RIP compatible terminal and is running
Searchlight in RIP mode.

'RipVers' is a three-byte value indicating the RIP terminal version that was
detected on the remote end. The version number is three binary values
correspoding to a three-part version number. For example, if the RIPterm
version is "1.50.02", then the three values you would find in the RipVers
array are 1, 50 and 2, respectively (these are binary numbers, not ASCII
characters).

Searchlight will only go into RIP mode if it can read the RIP version number
from the remote terminal. Therefore, RipVers is guaranteed to contain a
valid version number if 'RipOn' is true.


       Altmenupath: string[45];         { Alternate path to menu files }

This is the alternate menu path supported in Searchlight 3.0.


       Protocol_Update: boolean;       { set if proto chart updated for 3.0 }

As noted above, Searchlight 3.0 makes a change to the 'Proto' array the
first time it is run. After the change is made, this variable is set to
TRUE to indicate that the transfer protocols have been updated, to prevent
them from being updated again.

If you write programs that accesses the external protocols and you want your
programs to be compatible with either Searchlight 3.0 or Searchlight 2.x,
then you should check the Protocol_Update variable to determine whether the
protocol array has been updated for Searchlight 3.0 (contains both internal
and external protocols) or not.



USER File:

The header record of the user file is used to store the netmail setup
information from the CONFIG program, including the Sysop's real name:

type UserHeader = record       { file header info }
       root: TreeRootType;       { tree root info }

       { Netmail Fields }
       Origin: array[1..5]
         of FidoAddressType;   { primary & alternate addresses }

       BadMail: string[25];    { Where to send bad messages }

       originate,
       reply,
       unlisted,
       crash,
       routeedit: Attribset;   { Netmail function security attributes }

       SysopName: string[25];  { Sysop's real name }
       pad: array[1..4] of byte;
     end;

To read or write the header record, use these new functions found in the
USERS unit after opening the user file:

  Procedure ReadUserHeader (var header: userheader);
  Procedure WriteUserHeader (var header: userheader);


The user records themselves contain new fields for holding a netmail routing
address and an internal protocol for message downloads:

       NetAddr: AddressType;   { netmail routing address }
       InProto: ProtocolType;  { protocol for internal xfers }

Searchlight 3.0 reserves eight bytes of data in the USER record as QWK mail
options. These fields aren't use internally by Searchlight; they are
available for external QWK mail doors to use, as an alternative to creating
a separate user file. The fields available are:

       QWKProtocol: byte;      { Protocol: 0=Zmodem 1=Ymodem 2=Xmodem }
       QWKArchiveType: byte;   { Archiver: 0=ZIP }
       QWKPacketNum: byte;     { Packet Number }
       QWKName: byte;          { Naming Convention: 0=Suffix 1=Prefix }
       QWKIndexes: byte;       { Generate Indexes: 0=Yes 1=No }
       QWKFromYou: byte;       { DL Mail from you: 0=Yes 1=No }
       QWKMarkNew: byte;       { Mark new messages as read: 0=Yes 1=No }
       QWKPacketType: byte;    { Packet type: 0=QWK 1=Text }

Searchlight 3.0 does feature an internal command, 144, which brings up an
editing screen where these options may be viewed or edited by the user. QWK
doors can take advantage of the internal function rather than code their own
options screens.

Since the QWK fields are available to any application, if you use these
fields in a QWK door, you should stick to the definitions used here and you
should be aware of the possibility that other QWK doors may be using the
same areas. Therefore, do not use these areas to store information except
as defined here.



Message Files:

The message header type adds the following field:

       Addr: AddressType;    { forward or expanded address info }

This field overlays the area used by the "FwdFrom" string in previous
versions.

'Addr' is a multipurpose field consisting of a string and a type byte. By
default, the type byte is 0, and the string is either blank, or, if
nonblank, contains the same value as the FwdFrom field in previous versions.

Type bytes 1 and 2 are used for netmail. Searchlight 3.0 stores netmail
messages in the MAIL subboard, just like ordinary messages: only the type
byte, Addr.Atype, identifies netmail messages. For incoming netmail
messages, the type byte is 1. For outgoing messages, the type byte is 2. The
string 'Addr.Data' contains either the source or destination fidonet address
in plain text format (Zone:Net/Node or Zone:Net/Node.Point); for example,
"1:107/252" or "250:500/1".

Searchlight 3.0's netmail program posts incoming netmail messages on the
MAIL subboard by setting Addr.Data equal to the address from which the
netmail message originated, and setting Addr.Atype to 1. Searchlight saves
outgoing netmail by setting Addr.Data equal to the destination address, and
Addr.Atype equal to 2. When exporting, the Netmail program searches the MAIL
subboard for messages with Addr.Atype equal to 2, and exports those messages
as netmail.

Searchlight 3.0 only writes outgoing messages (Addr.Atype equal to 2) on the
MAIL subboard. Posting outgoing netmail messages on other subboards will have
no effect. However, Searchlight 3.0's SLMAIL program does set the incoming
netmail flag (Addr.Atype=1) and origin address for incoming echomail on any
echomail subboard; this allows Searchlight to execute private netmail replies
to public echomail messages.

The reason why Searchlight 3.0 defines netmail addresses with a plain text
string and a type byte is to allow for other kinds of addresses in future
versions. The only currently defined type bytes are 0, 1 and 2. Future
releases may define other values for other kinds of addresses. If you wish
to write applications that use the Address field for other kinds of
addresses, contact Searchlight Software first before using other address
type bytes.


       Crashmail: boolean;   { set if crash mail }

This byte in the message header is set if the message is an outgoing
crashmail message. It is used only for netmail messages and has no effect on
local messages.



File Directory Files:

       Skipscan: boolean;      { skip duplicate file scan }

This variable is added to file directory files to indicate that the
duplicate scan on uploads should be skipped (ie. FALSE means perform the
scan, TRUE means skip the scan for that directory).



(c) Copyright 1993 Searchlight Software